T072, 13.1: the bundled PostgreSQL server, the local install's own child (plan 034) - #69

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

Arc: neutral-product-standalone-operability

Plan 034 (specs/034-opendox-standalone-operation/tasks.md, read at openxFactory main 91e4685f), phase-3 slice P3-I, install mode and the bundle:

• T072 (#1144's 13.1): the bundled PostgreSQL server, as T007 batch H's 13.1 addendum reads (openxFactory#1206 → f99a2097).
• Falsifier: F13.1's TCP-listener block, which reads the kernel's socket table at run time, and its runtime status block.
• After: T070 (openDox-code#67, landed as 66ff7257). It was stacked on T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67's branch; the holder has retargeted it to main, and 57b7ed8f merges main 66ff7257, so this diff is T072 alone.

Ruled:

• R1Q22 (a), 5817152735;
• R1Q16 (i)–(iv), 5850003126;
• the phase-3 draft-ahead widening, 5901112350.

Claimed on openxFactory#656 in 5901575394. Authored ahead as a DRAFT, which did not go READY before T063 landed and the holder said so. T063 has landed (openxFactory#1218 → a883bbf6, 2026-10-02 23:37:43Z), which closes phase 2, so phase 3 is open. #60 (7ff434d9) and #67 (66ff7257) ahead of it have landed.

What it does, by R1Q16's four parts

• (i) The document server starts it as its own child, and reports it.
  • opendox generate-and-open --local (or OPENDOX_INSTALL_MODE=local) starts postgres as a direct child of the process serving the document surface. It uses subprocess.Popen and never pg_ctl, which would re-parent it.
  • It prints the socket, the pid and what it migrated.
  • runtime status reports database_bundle (data_dir, socket_dir, pid). It reads the pid from the server's own postmaster.pid and believes it only while a postgres runs there.
• (ii) Started and migrated, and nothing more.
  • initdb runs once per data directory.
  • An idempotent bootstrap makes the database and the SERVED role. Its grants are the compose stack's (init-runtime-role.sh): CONNECT, USAGE on public, and DML on what the owner creates, by default privileges.
  • Then migrations.MigrationRunner runs as the owner, with the served role and database declared. The run narrows the ledger to SELECT for the served role and verifies its access, exactly as a hosted runtime migrate does.
  • runtime migrate under local migrates the bundle too.
• (iii) It ships as the opendox[local] extra, which is opendox[runtime] plus pixeltable-pgserver>=0.6.0 (RULED, openxFactory#656 5916000030 item 2). The test extra joins it, so F9.1's .[test] install still runs every case.
• (iv) It stops with the entry point.
  • SIGTERM is read as the Ctrl-C the serve loop already stops on, followed by a PostgreSQL fast shutdown (then an immediate one, then SIGKILL, each bounded).
  • The backstop is PR_SET_PDEATHSIG on Linux, so a SIGKILLed entry point still takes its server with it.
  • The server runs in its own session, so a terminal's Ctrl-C reaches the entry point, and the stop happens in order.

13.1's fixed identity

• The data and socket directories live under OPENDOX_STATE_DIR, at <state>/postgres/data and <state>/postgres/run.
  • The setting is new. It defaults to $XDG_STATE_HOME/opendox, else ~/.local/state/opendox, and must be absolute, because the server's process and a runtime status run from elsewhere must derive the same socket.
  • A state directory too long for the kernel's sun_path is refused, naming the setting.
• No TCP listener: listen_addresses is empty, and the socket directory is narrowed to 0700.
• Peer authentication (RULED, openxFactory#656 5916000030 item 3, "Peer auth + accept (Recommended)"):
  • initdb runs with --auth-local=peer --auth-host=reject.
  • Before every launch the bundle rewrites pg_hba.conf and pg_ident.conf (atomically, mode 0600). pg_hba.conf holds one rule, local all all peer map=opendox, plus host … reject for IPv4 and IPv6. pg_ident.conf maps the running OS user, and nobody else, to opendox and opendox_runtime.
  • The kernel reports the connecting uid, so the DSNs carry no password because there is none. A cluster an older build left as trust is put back to peer on its next start.
• Both DSNs are supplied: two users (owner opendox for migrations, opendox_runtime for serving) over the one socket, with port spelled so a stray PGPORT cannot redirect libpq. They pass T071's three checks for the reason those exist: one dialect, one database, and never one credential in both settings.
  • An operator DSN given beside local is refused by name. It is added to T070's HOSTED_ONLY_SETTINGS, a holder reading on openxFactory#656 that Brett may overrule.
• A second entry point on the same state directory is refused, naming the running pid. One install's database belongs to one entry point at a time.

The migrations gap (assigned to T072 by the holder)

• The migrations were not package data. migrations/ sits at the repository root, and only the image copies it (WORKDIR /app), so pip install "opendox[local]" run outside a checkout had nothing to apply.
• Now pyproject.toml's [tool.setuptools.data-files] maps migrations/*.sql into the wheel's data directory (share/opendox/migrations). The root migrations/ does not move.
• config.migrations_dir resolves an unset OPENDOX_MIGRATIONS_DIR in this order:
  1. migrations wherever the working directory has one (a checkout, or the image's /app), which is today's default, unchanged;
  2. otherwise the copy the installed distribution's RECORD lists (packaged_migrations_dir);
  3. for an editable install, which installs no data files, the source tree's own migrations/.
• The canonical digest gate is what proves any copy found is the pinned one.
• test_a_wheel_install_migrates_its_bundled_server_outside_a_checkout:
  • builds this package's wheel offline (--no-build-isolation, --no-index);
  • installs it under a --prefix outside the checkout;
  • runs from a directory with no migrations/, asserting that opendox is the wheel's copy and that the migrations dir is under the prefix's share/opendox;
  • migrates the bundled server there (applied == ["0001", "0002"]).

The server package (RULED, openxFactory#656 5916000030 item 2: "pixeltable-pgserver (Recommended)")

• pixeltable-pgserver 0.6.0, the maintained fork of pgserver, uploaded 2026-07-14. Apache-2.0, as its dist-info LICENSE and OSI classifier say. It carries PostgreSQL 16.14 under the PostgreSQL License (initdb --version and postgres --version from pixeltable_pgserver/pginstall/bin). It also carries an 18.4 under pginstall18/, which this package does not use.
• Only its binaries are used, found with importlib.util.find_spec("pixeltable_pgserver") without importing it. Its own manager is not used, because:
  • it daemonizes through pg_ctl, against (i);
  • it stops from atexit, which SIGTERM never runs, against (iv);
  • it may put the socket under the user's runtime directory, opened to 0777, against 13.1.
• Linkage, re-verified on the installed wheel (readelf -d, ldd):
  • postgres needs libz, libpthread, librt, libdl, libm, libc;
  • initdb needs those less libz and libdl, plus the wheel's own vendored libpq. That libpq resolves through RPATH $ORIGIN/../../../pixeltable_pgserver.libs and itself needs only libc, libm and libpthread;
  • the server's loadable modules need libc, and one needs the vendored libpq.
    So the system libraries are the C library and libz only: no system PostgreSQL, no ICU.
• Its floor and its size:
  • Wheels exist for cp310 to cp314, on Linux x86_64 and aarch64, macOS and Windows.
  • The Linux wheels are tagged manylinux_2_27 and manylinux_2_28, so they need glibc 2.27 or later. That is the tag's floor. The highest GLIBC symbol any binary or module needs is 2.25, by objdump -T.
  • Each wheel is about 24.7 MB (the cp312 x86_64 wheel is 24,704,230 bytes), because it carries two server majors.
• It pulls in fasteners, platformdirs, psutil and typing-extensions, which nothing here imports. All four were already pinned.
• Superseded: pgserver 0.1.4 carried PostgreSQL 16.2 and had no wheel after cp312 (Copilot r4139811507 and r4139811528, both now resolved with this ruling cited). Also rejected: postgresql-binaries, which links the system's ICU and untars at first use, and pgembed, which is PostgreSQL 17.

Outside src/ and tests/

• pyproject.toml: the local extra, the test extra joining it, setuptools>=70.1 in test (the wheel test's offline build; 70.1 is the first release that builds a wheel with no wheel package), and the data-files map. It is a single-writer file (T057 → T072). T057, openDox's own validator and its input set (7.1, 7.1a, 7.1b, 7.2) (plan 034) #58 (T057) adds package data there, and the merge-from-main round takes it.
• constraints-cpython312-linux.txt, in its own commit as its header asks. It was extended under its own pins in a clean 3.12.3 venv (psutil==7.2.2, platformdirs==4.12.2, fasteners==0.20 and setuptools==84.0.0 new). At 84a6c041 it was re-resolved in a clean environment under the pins less pgserver. The one line that moved is pgserver==0.1.4 → pixeltable-pgserver==0.6.0.
• deploy/ — one line, and the task requires it. deploy/compose/.env.example gains OPENDOX_STATE_DIR=, because test_every_runtime_setting_is_documented_in_env_example requires every SETTINGS entry there. The compose stack is hosted and never reads it. docs/: untouched.
• Not touched: serve.py (T073 adds the install block) and validate.yml. It already installs .[runtime,test], and test now carries local.
• Existing tests changed:
  • tests/test_doxbench_entrypoint.py stands the bundle in, with a tripwire. Its cases test the model port, which reads nothing from the store (R1Q16 (ii)).
  • T070's test_install_mode.py and test_install_mode_entrypoint.py stop passing DSNs beside local.
  • test_runtime_surface.py declares opendox.runtime.bundle stdlib-only at import, because opendox.cli imports it and opendox --help runs with no extra installed.

The falsifier

F13.1's runtime status block and its TCP-listener block, verbatim in their assertions (f13-1-local.sh), against a server generate-and-open --local started in the background, with no broker and no operator database, under set -euo pipefail.

Since the merge round (19e32f0c), the start is the REAL entry point. It is python -m opendox.cli generate-and-open --local, with the validator on, over T050's tests/fixtures/plain-documents copied into a fresh repository, as F13.1's preamble does. The stand-in driver is deleted. One deviation remains, and it does not weaken a check:

• Generation is stood in. Retired at 19e32f0c. Until then the start went through tests_runtime/local_entrypoint_driver.py, because this stack's base predated T055/T056's standalone generate.
• The pid comes from runtime status. The TCP-listener block reads the server's pid from runtime status's database_bundle, not from caps.json. /capabilities' install block is T073's, so F13.1's caps.json block is T073's to run.
• The corpus is a one-file stand-in. Retired at 19e32f0c: it is T050's fixture now.

BEFORE is #67's head b50e3b1; AFTER is this branch:

=== BEFORE (b50e3b1)
ready=1
runtime status rc=1
AssertionError: no bundled database answered: None OPENDOX_DATABASE_URL is required and is not set: …
FAIL status-block
AssertionError: the bundle reports no server pid: None
FAIL tcp-listener-block
=== AFTER (this branch, set -euo pipefail, exit 0)
ready=1
runtime status rc=0
PASS status-block
  server pid 638810, sockets ['3692911'], TCP LISTEN rows: none
PASS tcp-listener-block
PASS stops-with-entry-point (pid 638810 gone)
--- server stdout:
  database /tmp/tmp.v0wydKm5Zm/postgres/run (bundled, pid 638810, migrations applied now: ['0001', '0002'])

T070's F13.1 refusal probes and F13.1's load_settings block still pass on this branch (F13.1 REFUSALS + T070 PAIR: ALL PASSED).

In the suite, tests_runtime/test_bundled_postgres.py runs the same two blocks on the same background launch, and adds three checks: the server's PPid is the entry point's pid (i), the socket directory is 0700, and SIGTERM ends the entry point with exit 0 and the server gone (iv). Beside that it has a SIGKILL case (the parent-death backstop), the second-server refusal, runtime migrate under local, the wheel case above, and the layout and refusal cases. Under CI it fails rather than skips if the server is missing, because validate.yml pins EXPECT_SKIPPED=11 exactly.

A mutant of each new refusal and guarantee, killed

Each mutant was applied alone, and test_bundled_postgres.py plus test_install_mode.py were run with -x, with a 240 s bound so a hang could not pass for a kill:

A defect this PR's own test found in itself. The first cut of the wheel case ran pip install --prefix without --ignore-installed. pip then read the suite's own editable opendox as the installed copy of the same project and uninstalled it, emptying the environment the suite runs in (measured: pip list lost opendox and both console scripts). The flag is now there, with a comment, and the case asserts afterwards that the suite's own opendox still resolves.

The repo's own suite

Full python -m pytest -q, LANG=C.UTF-8, CI=true, against a postgres:16 like validate.yml's:

EXPECT_SKIPPED=11 holds exactly, and the floors allow the rise unchanged. The new module adds about 32 s to the run (ten cases, each server start about 1.5 s).

Merging #67's fix rounds. 95fe16f merges 32683e8, and 32db5d8 merges 525f61c: runtime migrate and reset refuse what a local install cannot be.

• 525f61c and this PR both rewrite load_migration_settings. The conflict resolves to this PR's structure: under local, the refusal is asked first, and only then is the bundle's migration DSN read. T070's reason is carried into the comment.
• The two merged cases set the local shape as this PR defines it, with the mode and the state dir and no operator DSN. Beside local a DSN is itself refused here, so a case that set one would have tested the DSN refusal instead of the broker or bind refusal it names.
• A mutant that drops the refusal from the migration loader fails all 7 merged cases.
• ac61596 merges 02dadc5, cleanly. With the runtime extra absent, status's early return now reports a local install's broker as not configured. The merged case uses this PR's local shape and also asserts that database_bundle is reported on that return: present for local, null for hosted.

Fix rounds 4 and 5: Copilot's twelve threads (5e52872, 96b2699f)

Copilot reviewed 95fe16f, 32db5d8 and ac61596a and opened twelve threads. Ten are fixed, answered and resolved. The new cases are in tests_runtime/test_local_lifecycle.py (new, hermetic), plus two in test_bundled_postgres.py.

• Migrations (r4139811473, r4139880241).
  • An explicit OPENDOX_MIGRATIONS_DIR is used as given.
  • Unset, a local install uses only its own installation's copy, never the working directory's. That copy is the source tree __file__ came from first, then the RECORD of the distribution that holds the running module. Where there is none, it is refused.
  • A hosted install's default is unchanged (13.6).
• The pid (r4139811555, r4139938402).
  • A pid is believed only when /proc proves it is an executable named postgres running in this data directory. A proven-stale lock is removed before the launch.
  • Where there is no /proc, nothing is believed, and PostgreSQL's own interlocks stand. The price is a status with no pid on macOS and the BSDs, recorded in the thread.
• initdb (r4139880213): it runs into an attempt directory that is renamed into place only on success. Abandoned attempts are removed. A non-cluster data/ is refused and left alone.
• start() (r4139880279): every phase is one guarded operation, and every failure is the one named refusal, with its phase and class.
• Interrupts (r4139880267): SIGTERM or Ctrl-C anywhere in the local lifecycle is a clean stop, exiting 128 + the signal number. A served run still exits 0.
• Refusal wording (r4139880298): broker settings and DSNs are two classes, each with its own reason.
• State dir (r4139938444): an unknown ~user, or no home, refuses naming OPENDOX_STATE_DIR.
• Test helper (r4139811584): bounded by a selector. With a silent 8 s child and a 1 s deadline, it returned after 1.0 s where the old loop took 8.0 s.

Evidence:

• Against ac61596's source, 17 of round 4's first 18 cases fail; the one that passes is the unchanged hosted default. Round 5's cases fail against 28bdccd.
• Mutants: 23 of round 4 and 5 of round 5, all killed (runs/mutants-t072-r4.txt, -r5.txt in the writer's workdir).

Round 6 (a0fb7c8d): Copilot's review at 28bdccd9 opened two more threads.

• The unknown-_serves point was already fixed at 96b2699f; it is answered and resolved.
• The pyproject note named a function that no longer exists. It now names installation_migrations_dir, and the packaging case checks every opendox.runtime.config.<name> pyproject names.
• 4aed6278 merges T070's 026f00ea, a docstring change.

Round 7 (0f77d5c1): Copilot's review at a0fb7c8d opened three threads, all fixed and resolved. SonarCloud raised one reliability finding.

• libpq's environment. Every PG* variable is lifted out of os.environ for the duration and put back afterwards, around generate-and-open --local's lifecycle and the runtime verbs under local. PGHOSTADDR, PGSERVICE and PGOPTIONS can no longer redirect the bundle's connections. The real entry point and status are proven with all three set.
• The socket's path. The resolved state tree must be this user's own and writable by no one else. Every ancestor must be owned by the user or root, and sticky where others can write it; a group-writable ancestor of the user's own group is allowed. Symlinks inside the tree are refused before any chmod.
• A relative HOME is refused for the default state directory.
• SonarCloud S6466 (reliability): server_binaries no longer indexes a list.
• Evidence: 8 new cases fail against a0fb7c8d, and 11 mutants are killed.

Round 8 (379fbb14): Copilot's review at 0f77d5c1 opened two threads, both fixed and resolved.

• A group-writable ancestor is refused whatever its group, because a primary group can have other members.
• The configured path is checked as configured, as well as resolved: both chains' ancestors, every link's owner, and no .. anywhere.
• Evidence: 5 new cases fail against 0f77d5c1, and 5 mutants are killed.

Round 9 (84a6c041) applies Brett's two rulings, openxFactory#656 5916000030 items 2 and 3: the carrier and peer authentication, as described above.

• The server confirms it, in its own views:
  • pg_hba_file_rules has exactly the one peer rule (with map=opendox) and the two rejects;
  • pg_ident_file_mappings has exactly the two mappings, for this OS user;
  • system_user is peer:<os user> for both roles.
• The map decides. The same OS user asking for a role outside the map is refused (peer authentication failed). A non-root suite cannot connect as a second OS user, so for that case the map, read back from the server, stands: it names no other user.
• Evidence: 13 new cases fail against 379fbb14. 9 mutants are killed:
  • initdb trust;
  • no map;
  • a trust rule;
  • a wildcard system user;
  • a third role;
  • no re-assertion;
  • any name admitted;
  • files 0644;
  • the old carrier.
    The auth mutants are also killed by the real-server cases alone.

Round 10 (f8e6e9e9): Copilot's review at 84a6c041 raised three points, all fixed.

• An existing postgres/data joins the tree check, a broken link included (r4147680113, resolved).
• Missing parent directories are created exactly 0700 whatever the umask. mkdir(parents=True) under umask 0002 made them group-writable.
• Readiness requires the data directory's lock file to name the launched child, so a racing loser cannot adopt the winner's socket.
• Evidence: 6 new cases fail against 84a6c041, and 4 mutants are killed.

SonarCloud S2115, ACCEPTED, as ruled.

• Issue: AaDvyyOCiqwq-gAw53M3, python:S2115, "Add password protection to this database", on src/opendox/runtime/config.py DatabaseBundle.dsn.
• New status: accept (SonarCloud now reports it RESOLVED). Set with the SonarQube tool on openxFactory#656 5916000030 item 3's authority.
• Rationale: the DSN has no password because the server authenticates Unix-socket connections by PEER. The kernel verifies the connecting uid (SO_PEERCRED), and pg_ident.conf maps only this install's OS user to the two roles. The socket directory is 0700, the server has no TCP listener (listen_addresses is empty), and every host connection is rejected. The same rationale is in the DSN's docstring.
• Gate: after the change, SonarCloud reports the PR's quality gate OK on every condition.

Merge-from-main round (fe232fe, 19e32f0c; 2026-10-02)

Phase 2 has landed. This branch now carries #67's c8fac05e, which carries #60's adeb6fed and main 047bb4fa (T054 to T058, T055's follow-up #70 and T056's standalone test). Git auto-merges pyproject.toml (main's validator package data beside this PR's local extra and data files), src/opendox/cli.py and tests/test_doxbench_entrypoint.py without a conflict. Four edits followed, all in 19e32f0c:

1. The stand-ins in tests_runtime/local_entrypoint_driver.py go. The driver is deleted. Its stand-ins patched names T055 has since replaced, so on the merged tree they stood in for nothing, and all three background cases failed: the real corpus-root check refused the stand-in corpus. test_bundled_postgres.py now runs the real entry point over T050's fixture, with the validator on.
2. Every cheap refusal comes before the database start. Main's T055 added _refuse_empty_source_options, so the local path asks it before it builds the bundled server. tests/test_projection_seams.py's empty-option case carries a tripwire bundle, so a regression neither starts a server nor passes.
3. No child touches the user's state directory. T070 gave four phase-2 callers --local, and here --local starts the bundled server, whose OPENDOX_STATE_DIR defaults to the user's ~/.local/state/opendox. tests/standalone_child.py now gives every child a fresh, short, private state directory under /tmp and removes it when the child stops. Measured before: three children of T056 and T058 initialized a cluster in the (sandboxed) default state home.
4. T056's case 3 asserts it: while serving, its bundled server's data directory is under the child's own state directory, and the directory is gone after the stop.

• Mutants, all four killed: the refusal dropped; no private state dir; the dir not removed; the fixture not a repository.
• Full suite: 3195 selected, 3184 passed, 11 skipped, 0 failed. Nothing is left under ~/.local/state/opendox or /tmp/odx-child-*.

Merge of #67's fix rounds (94254b18, 6eb0bbdb; 2026-10-02)

94254b18 merges #67's cdf7382b, which carries #60's c39d960e (a PostgreSQL scheme libpq would not read as a URI is refused). cdf7382b itself means a --local caller inherits none of the runner's runtime settings. There were two docstring and setup conflicts, and both were resolved by keeping both sides:

• tests/standalone_child.py: the code merged cleanly in the needed order. The child's environment first drops every SETTING_NAMES entry, and only then is OPENDOX_STATE_DIR set to the child's own directory.
• tests/test_projection_seams.py: the empty-option case scrubs the settings and keeps this PR's bundled-server tripwire.

6eb0bbdb changes #67's harness probe. On #67 it asserted that a child sees no runtime setting. Here every child is given exactly one, its private state directory. The probe now also exports a runner state directory, and asserts three things:

• the child sees exactly OPENDOX_STATE_DIR among the runtime settings;
• its value is the child's own Child.state_dir, not the runner's;
• the directory is gone once the child has exited.

Evidence:

• Mutants, all four killed, under an exported hosted install's settings:
  • the child keeps the runner's settings;
  • the scrub runs after the state dir is set;
  • the runner's own state dir is passed through;
  • the in-process case does not scrub.
• Exported settings: the child-driven modules (tests/test_standalone_generate_path.py, tests/test_post_render_validator.py) pass whole with a hosted install's settings and a runner OPENDOX_STATE_DIR exported.
• Full suite: 3204 selected, 3193 passed, 11 skipped, 0 failed. Nothing is left under ~/.local/state/opendox or /tmp/odx-child-*.

Fix round 11: nothing is made through a path the tree check would refuse (0488f5bd, then fedfa75d)

Copilot's review at 19e32f0c opened one thread, which is real (reproduced) and is now answered and resolved. _prepare_directories made the missing postgres/run before the tree check judged the path, so a component it refuses had already been written through: another user's link, or a 0777 directory. In a sticky parent such as /tmp, another user could also plant the state directory's name between the check and the mkdir. The fix:

• What exists is judged before any write. _refuse_an_unsafe_tree(existing_only=True) runs the link-ownership loop first, so even a broken foreign link is named. The whole tree is judged again afterwards, before the socket directory's chmod.
• Missing components are made by descriptor. _make_private_directories makes each one relative to its parent's descriptor and opens it with O_NOFOLLOW. fstat must show it is this user's alone before anything is made beneath it. A planted link, non-directory or foreign directory is the named refusal: never followed, never re-moded.
• No mkdir/chmod window. Each component is born 0700 under a umask of 077, and the umask is put back afterwards.

Evidence:

• New cases: six, in tests_runtime/test_local_lifecycle.py. All fail against 19e32f0c's bundle.py and pass here.
• Mutants: seven, all killed.
• Full suite: 3210 selected, 3199 passed, 11 skipped, 0 failed.

fedfa75d merges #67's d1de1fd9 (its healthy-local status case reads either DSN form). On this branch that case uses the bundled server, so the conflict resolves to this side and changes no file.

Fix round 12: the auth files are exactly 0600, and the cluster runs on its own files (3426c753, then f66e5f82)

Copilot's reviews at 6eb0bbdb and fedfa75d opened two threads, both real and now answered and resolved.

• write_authentication's 0600 was only a creation request. The umask filtered it, and a stale temporary from an interrupted start kept its own mode or was written through as a link. Now the stale temporary is unlinked, the new one is opened O_CREAT | O_EXCL | O_NOFOLLOW, and its descriptor is fchmod-ed to exactly 0600 before anything is written. A link raced in after the unlink is a refusal, never followed.
• A reused cluster's postgresql.conf could redirect data_directory, hba_file and ident_file, for example to an outside trust file. The launch now pins all three on the command line, which outranks every configuration file.

Evidence:

• New cases: four in tests_runtime/test_local_lifecycle.py (umask, stale 0644, stale link, raced link) and one real-cluster case in tests_runtime/test_bundled_postgres.py. All but the raced-link case fail against fedfa75d.
• Mutants: six, all killed.
• Full suite: 3215 selected, 3204 passed, 11 skipped, 0 failed.

f66e5f82 merges #67's 105f2f12 cleanly. It adds an autouse fixture in tests_runtime/conftest.py that clears every runtime setting before each case, so a case wanting OPENDOX_STATE_DIR sets its own, as every one here already does.

The adversarial review of f66e5f82 (a9854078 to 21bde1af; 2026-10-02)

An adversarial review of f66e5f82 found nothing high. It found one medium, three lows and a note. Each is fixed in its own commit, each with a new case that fails without it and mutants that are killed. One more hermeticity fix came first.

• a9854078: the in-process local cases give themselves a short state directory. The doxBench entrypoint fixture and the empty-option case in test_projection_seams.py scrubbed the settings, and so fell back to the runner's default state directory. When that is too long for a Unix socket, configuration refuses it before the case is reached. Measured with a 90-character XDG_STATE_HOME: 4 errors and 1 failure. Each now sets its own short OPENDOX_STATE_DIR and removes it afterwards. Nothing is made in it, because the database is stood in. Both mutants are killed.
• M1, medium (e214477d): a comma in the state directory is refused. PostgreSQL splits -k on commas, and libpq splits a decoded host on them. The review reproduced sockets in two unchecked directories, one of them 0777, while the checked 0700 directory stayed empty. config.database_bundle (every bundle's one derivation) now refuses a , from OPENDOX_STATE_DIR, XDG_STATE_HOME or HOME, without repeating the value.
• L1 (c4f5df3c): the carrier is pinned to pixeltable-pgserver>=0.6.0,<0.7, and another major is refused by name. Before an existing cluster is used, the server's own postgres --version is asked against its PG_VERSION. Another major, or a server that does not say, is a named refusal, before anything is written. 4 mutants are killed.
• L3 (b2d80e94): the directory creation starts from is judged by its descriptor. _make_private_directories now fstat-judges the base it opens with _unsafe_because before the first mkdir. That is the install's own rule for the state directory and below, and the ancestors' rule above it. This makes round 11's rule hold inside the function itself. 2 mutants are killed.
• L2 (9e2f3030): the local verbs judge their socket before connecting to it. runtime status, migrate and reset connected to whatever answered at the bundle's socket path. Reproduced here: status on a 0777 tree whose run linked to another bundle's socket reported that bundle's applied migrations and exited 0. The fix:
  • bundle.refusal_before_connecting asks the start's tree check (now bundle.refuse_an_unsafe_tree) of what exists. It then asks for a live server of THIS data directory: its own postmaster.pid must name a live postgres whose working directory is this data directory, listening at this socket directory.
  • Status's database reads "not probed: <reason>" for a local install that fails this check, including one with no server running. It used to read "unreachable: …", found by connecting.
  • migrate and reset refuse as local-bundle-unverified. Hosted is unchanged.
  • The status database block is re-indented under the new branch; git diff -w shows only the branch.
  • 7 mutants are killed.
• The note (21bde1af): no replication connection, logical or physical. Fixed, not only reworded. authentication_files' docstring said a replication connection is refused. A physical one was refused, but a logical one (replication=database) was accepted as peer:<user>, and IDENTIFY_SYSTEM answered (measured). No pg_hba.conf rule can tell it from an ordinary connection. So the launch sets max_wal_senders=0, and the docstring now says both kinds are refused by the server. The mutant is killed.

Full suite: 3236 selected, 3225 passed, 11 skipped, 0 failed. Nothing is left under ~/.local/state/opendox or /tmp/odx-*.

Fix round 13: the server is found as the installed distribution's own files (28e195b9)

Copilot's review at f66e5f82 opened one thread, which is real and is now answered and resolved. server_binaries used importlib.util.find_spec, which follows sys.path. Under python -m opendox.cli that starts with the working directory, and a corpus checkout is where it runs. So a checkout holding an executable pixeltable_pgserver/pginstall/bin/postgres was run as the database server.

The carrier is now looked up by distribution name (importlib.metadata), on sys.path without the working directory. Both binaries must be files its RECORD lists, inside it and executable.

Evidence:

• New case: the working directory holds an importable package and a forged .dist-info, and the server is not taken from it.
• Reworked lookup case: four refusal shapes.
• Before: 6 of the 8 fail against find_spec.
• Mutants: 4 killed, 1 equivalent.
• Full suite: 3240 selected, 3229 passed, 11 skipped, 0 failed.

Fix round 14: a named platform gate, resolution failures as reasons, no pid behind a refused tree (bf9bcb08)

Copilot's review at 21bde1af opened three threads, all real and now answered and resolved.

• A named platform gate. The bundle is a POSIX design, but the carrier ships Windows wheels, where a start failed as an AttributeError. bundle.unsupported_platform() names the missing primitives (os.getuid, O_DIRECTORY, O_NOFOLLOW, os.fchmod, mkdir with dir_fd, socket.AF_UNIX). A start and the local verbs' socket check ask it first.
• Resolution failures are reasons. refusal_before_connecting() names a symlink loop (RuntimeError) and an embedded NUL (ValueError) as reasons, beside OSError.
• No pid behind a refused tree. bundle.report() reports a pid only behind a verified tree. A postgres/data linked to another live bundle had reported that server's pid.

Evidence:

• New cases: three hermetic ones, and a linked-data shape with null-pid assertions in the real verbs case.
• Mutants: eight, all killed.

Merge of main after #67 landed (57b7ed8f; 2026-10-03)

#67 (T070) landed as a squash, 66ff7257, after #61 (T078, 8a98e317). Main thus holds T070's content as one commit this branch's history never saw, and a plain merge against the old base 047bb4fa conflicted in ten files where both sides carry the same T070 text.

So the merge is computed against the T070 state this branch already held, #67's 105f2f12: git merge-tree --write-tree --merge-base=105f2f12 HEAD origin/main. It is recorded with both parents. The base is sound because git diff 25262459 66ff7257 (#67's last branch head against its squash) names only #61's three files. Against it the merge is clean:

• 18 files take main's changes since 105f2f12: T088, the lens's two seed actions are offered only where a binding answers them (R1Q19 (a)) (plan 034) #65 T088, T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71 T085, T078, 16.1: the OpenAI-compatible dialect joins DIALECTS (plan 034) #61 T078, and T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67's --local in T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71's test.
• 17 of them are byte-identical to main's. src/opendox/cli.py is the one merged file: main's two doxbench_defaults registrations sit beside this branch's local path.
• No standalone generate-and-open child main brought in lacks --local. T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71's case gained it in T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67's merge. T088, the lens's two seed actions are offered only where a binding answers them (R1Q19 (a)) (plan 034) #65's lens test runs generate and serve.build_server. T078, 16.1: the OpenAI-compatible dialect joins DIALECTS (plan 034) #61 runs no entry point. Under T072, T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71's --local child starts a bundled server in tests/standalone_child.py's private state directory.
• Full suite: 3327 selected, 3316 passed, 11 skipped, 0 failed.

Fix round 15: on Linux the parent-death signal is armed, or the server is not started (058d96ef)

Copilot's review at 57b7ed8f opened one thread, which is real and is now answered and resolved. ctypes reports a failed prctl() by returning -1, never by raising (a seccomp denial, say), and the child ignored it. A killed entry point could then orphan the server, against R1Q16 (iv).

The fix:

• A failed prctl is a refusal. The child now raises on a nonzero return. subprocess re-raises that as SubprocessError, which _launch names as the refusal "could not be given its parent-death signal", with no server process left.
• A Linux C library with no prctl is the same refusal, where it used to fall back silently. Other platforms are unchanged.

Evidence:

• New case (Linux): a stand-in prctl that returns -1. The start refuses by name, and the stand-in server never runs.
• Mutants: both killed.
• Full suite: 3328 selected, 3317 passed, 11 skipped, 0 failed.

Merge of main after #62 landed (085ba0b0; 2026-10-03)

085ba0b0 merges main 2fc714d2 (#62, T079). #62 changes only doxbench_binding.py, doxbench_intake.py, doxbench_provider.py and test_model_provider_broker.py, none of which this branch touches, so the merge is clean. It runs no generate-and-open child, so it needs no --local. Full suite: 3346 selected, 3335 passed, 11 skipped, 0 failed.

Fix round 16: a local install's served role and database are the bundle's own (3ebccb3c)

Copilot's review at 085ba0b0 opened one thread, which is real and is now answered and resolved. Under local, OPENDOX_RUNTIME_PG_ROLE could replace the bundle's served role in the settings. The migration run narrows the ledger privileges of exactly that configured role, while the bundle bootstraps opendox_runtime with the default DML and its served DSN connects as opendox_runtime. So OPENDOX_RUNTIME_PG_ROLE=pg_read_all_data left opendox_runtime able to rewrite opendox_schema_migrations.

refuse_what_a_local_install_cannot_be (asked by both loaders and by generate-and-open --local) now accepts two settings only unset or naming the bundle's own:

• OPENDOX_RUNTIME_PG_ROLE must be opendox_runtime;
• OPENDOX_SERVED_DATABASE must be opendox, since it declares the same identity.

Hosted is unchanged.

Evidence:

• New case: both settings, through both loaders.
• Mutants: both killed.
• Full suite: 3350 selected, 3339 passed, 11 skipped, 0 failed.

Merge of main after #74 landed (52a2b8dc; 2026-10-03)

52a2b8dc merges main 9a490405 (#74, T081), with no overlap. #74's standalone generate-and-open fixture already passes --local, since it landed after #67. Under T072 that child now starts a bundled server in the harness's private state directory.

• tests/test_chat_model_configuration.py: 49 passed.
• Full suite: 3399 selected, 3388 passed, 11 skipped, 0 failed.

Fix round 17: the /proc falsifier is gated, and a backslash in the map is pinned literal (4a9dbe95)

Copilot's review at 52a2b8dc opened two threads, both now answered and resolved.

• The /proc falsifier is gated. test_the_entry_point_owns_a_migrated_server_with_no_tcp_listener reads Linux's /proc, so it now skips where /proc is absent, as the other /proc and PDEATHSIG cases do. On Linux, and in CI, nothing changes.
• Backslashes are pinned literal, not escaped. The thread suggested escaping backslashes in pg_ident.conf. Measured against the bundled PostgreSQL 16.14, pg_ident_file_mappings reads "DOMAIN\alice", "alice\" and "a\\b" back as exactly those names, without error. The tokenizer treats a backslash specially only at the end of a line, never inside quotes, so escaping would map a different name.
  • The code is unchanged.
  • A real-server read-back case and a hermetic verbatim assertion pin the behaviour.
  • The escaping mutant is killed.

Full suite: 3402 selected, 3391 passed, 11 skipped, 0 failed.

main has since taken #63 (T080, 1130e996), whose five files (the doxbench model-provider family) do not overlap this branch. The PR stays MERGEABLE, and CI's merge ref includes it.

Fix round 18: one schema for both DSNs, and an uninspectable live pid fails closed (8986158e, c04690f8)

Copilot's review at 4a9dbe95 opened two threads. The holder accepted both, and both are now answered and resolved.

• 8986158e: both bundle DSNs name search_path=public. Left implicit, PostgreSQL's "$user", public let a reused cluster with a schema named opendox or opendox_runtime split the owner's ledger from the served role's reads.
  • New real-server case: both role-named schemas are created, then the bundle restarts. Both roles' current_schema() is public, they read one ledger, nothing is re-applied, and status is reachable with nothing pending.
  • Before: without the pin, the restart fails with RuntimeAccessMissingError.
  • Mutants: 2 killed.
• c04690f8: a live pid /proc will not describe is unknown, not "not ours". _identity raises _Withheld for anything but a vanished entry, and _remove_a_proven_stale_lock keeps the lock and refuses the start by name rather than unlinking a possibly live server's lock. With no /proc at all, PostgreSQL still judges.
  • New case: a live pid whose /proc links are withheld. It fails against 4a9dbe95.
  • Mutants: 2 killed.

Full suite: 3404 selected, 3393 passed, 11 skipped, 0 failed, run with LANG=C.UTF-8 and no GIT_*/XF_*.

Downstream, for the holder

• Out of scope, and not T072's: serve.py cannot bind ::1. This is pre-existing, measured at T071, 13.2 and 13.3: load_settings refuses a non-PostgreSQL DSN and a collapsed DSN pair (plan 034) #60's head f097fd8: gaierror [Errno -9] Address family for hostname not supported. serve.LOOPBACK_HOSTS lists ::1, but ThreadingHTTPServer is IPv4. Recorded on T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67 (T070) for a serve.py follow-up in that file's single-writer order. This PR does not touch serve.py.
• Done at the merge round: the driver's stand-ins are gone, and the probe runs the real entry point on tests/fixtures/plain-documents.
• For T073 and T075, which stack on this PR: a --local child built with tests/standalone_child.py gets its own state directory automatically. Any other --local caller must set OPENDOX_STATE_DIR itself.
• T073 reads database_bundle from the server object the entry point keeps (args.database_bundle) for /capabilities' install block.
• T074 runs F13.1 whole, caps.json block included.
• Overlap (gh pr diff -R opensoft/openDox-code): pyproject.toml (T057, openDox's own validator and its input set (7.1, 7.1a, 7.1b, 7.2) (plan 034) #58) and cli.py (T055, serve and generate standalone (5.5, 4.3 part) (plan 034) #59, and the T058 writer after it). They have landed, and this stack took its merge-from-main round after them. serve.py is not touched here.

🤖 Generated with Claude Code

Summary by Sourcery

Add a self-contained local installation mode that owns, migrates, reports, and cleans up its bundled PostgreSQL server.

New Features:

• Add a standalone local-install mode with a bundled PostgreSQL server managed by the document entry point.
• Expose bundled database location and process information through runtime status, including separate migration and serving credentials over a Unix socket.
• Package migrations and the PostgreSQL carrier in local-install wheels so installations outside a checkout can initialize and migrate their database.

Bug Fixes:

• Prevent local installs from using operator-supplied database or migration DSNs and from accidentally applying migrations from another working directory.
• Ensure stale or conflicting bundled-server state is detected safely and refuse multiple entry points sharing one state directory.

Enhancements:

• Enforce a state-directory layout, absolute-path and Unix-socket length constraints, local-only socket access, and no TCP listener.
• Manage bundled PostgreSQL lifecycle with child-process ownership, graceful shutdown, parent-death cleanup, and bounded startup failure handling.
• Resolve local and hosted migration sources independently while preserving the hosted migration default.

Build:

• Add the local and test dependency extras, pin bundled-server dependencies, and include migrations in built wheels.

Deployment:

• Document OPENDOX_STATE_DIR in the compose environment example.

Tests:

• Add end-to-end coverage for bundled PostgreSQL startup, migration, process ownership, lifecycle cleanup, socket security, refusal behavior, and wheel installation outside a checkout.
• Extend install-mode and runtime-surface tests for local settings, bundled database reporting, packaging, and lifecycle interrupt handling.